Back to Contents        Previous        Next






31. Iconiser

’Iconising’ is the result you get on pressing a window’s Close icon whilst holding down <shift> The window is converted to an icon on the Pinboard, from whence it can be re-opened by double-clicking on it (see User Guide). With later versions of RISC OS the same can be achieved by pressing a special iconiser button on the window ‘furniture’.

Your DrWimp application responds automatically to the Wimp’s ‘iconiser’ protocol and allows you to alter the text and sprite used - for customising. It does this by calling PROCuser_iconise whenever iconising action takes place.

If you do nothing, the iconised sprite will be the default one supplied by the Wimp (a framed question mark for an application window) and the default text beneath it will normally be the title of the window being iconised. However, if there is no window title text, or the text includes the word “untitled”, then the default text will be the name that you used for your application in FNwimp_initialise e.g. “YourApp”.

If you want to use a customised sprite and/or different text, then all you need to do is set the names of them in PROCuser_iconise, as follows. You will note that the skeleton !RunImage contains:

DEF PROCuser_iconise(window%,RETURN text$,RETURN spritename$)
ENDPROC


When called by the DrWimp library, these parameters will contain the window handle where the iconising action has taken place plus a default text and default sprite name. The text is straightforward - as mentioned above - but note that the Wimp will probably automatically truncate all text to the first 10 characters.

However, for iconising, the Wimp always uses sprites whose name begins with the prefix “ic_” e.g. ic_draw or ic_yourapp etc. The prefix “ic_” is added automatically by the Wimp. So, spritename$ only needs to contain the wanted sprite name without the prefix e.g. if your application’s declared name is “YourApp” then, when PROCuser_iconise is called, the default name in spritename$ will be “YourApp”.

If you do nothing then the contents of spritename$ will not change and the Wimp will, using the above example, be looking for an iconiser sprite called “ic_yourapp” - sprite names are not case-sensitive. If it finds one with the right name it will use it. Otherwise it will use the Wimp’s own default iconiser icon.

Conversely, to demonstrate iconiser customisation, let’s say that you want the text beneath the iconised window (whose handle is main%) to be “AppMain” and you want a sprite called “ic_neat” to be used. You would effect this simply by using something like:

DEF PROCuser_iconise(window%,RETURN text$,RETURN spritename$)
CASE window% OF
         WHEN main%
                  text$=”AppMain”
                  spritename$=”neat”
ENDCASE
ENDPROC

and, of course, you would have to supply sprites called “ic_neat” in the !Sprites/!Sprites22 sprite­files. That’s all there is to it. You can easily see that this can be used to show a different text and/or sprite for each of your application’s windows, if you wish.

However, please note that the Wimp does not allow sprite names to be greater than 10 characters. Hence, if you want to customise the iconiser it is vital that the name you use in spritename$ above does not exceed 7 characters - to allow for the prefix “ic_”. If the overall sprite name length does exceed 10 characters then the Wimp will truncate the name to the leftmost 10 characters and try to find a sprite name to match. If it cannot find one, the Wimp’s default iconiser sprite will be used instead. You will be warned if your intended customised sprite name is too long. (This point also explains why it can help to keep application names to no more than “!” plus 7 characters.)

(If you use !Fabricate - see Section 2.35 - the resulting customised skeleton application will include a rough (very!) sprite for iconising purposes, called
“ic_myapp“ - which is also included in the !MyApp skeleton. !Fabricate will also warn you about, but not prevent, your application name exceeding 7 characters.)







Top of page        Back to Contents        Previous        Next